home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr47 / wasm223.zip / OBJECT.DOC < prev    next >
Text File  |  1993-05-04  |  10KB  |  236 lines
  1.  
  2.  
  3.                                Object File Macros
  4.                                ------------------
  5.  
  6.      The macros defined in the file OBJECT.INC allow WASM to create
  7.      standard object modules that can be linked with object modules from
  8.      other languages.  The primary limitations of these macros are that
  9.      external symbols cannot be referenced and there are certain
  10.      limitations in the way local data may be accessed.
  11.  
  12.      I have successfully used these macros to produce WASM subroutines for
  13.      QuickBASIC version 4.0 (using LINK.EXE version 3.65), and Turbo C++
  14.      version 1.0 (using TLINK.EXE version 3.0).
  15.  
  16.                                  General Layout
  17.                                  --------------
  18.  
  19.      The format of a WASM object module consists of the INIT macro first,
  20.      all PUBLIC definitions, the BEGIN macro, all assembler code and data,
  21.      and finally the END macro.  All assembler code and data must be
  22.      between the BEGIN and END macros.  Example:
  23.  
  24.          INCLUDE 'obj.inc'
  25.  
  26.          INIT    'MYFILE.ASM', '_TEXT', 'CODE', ALIGN_BYTE+COMBINE_PUBLIC
  27.  
  28.          PUBLIC  MyProc1, '_MyProc1'
  29.          PUBLIC  MyProc2, '_MyProc2'
  30.  
  31.          BEGIN
  32.  
  33.        MyProc1 PROC FAR
  34.          ret
  35.          ENDP
  36.  
  37.        MyProc2 PROC FAR
  38.          ret
  39.          ENDP
  40.  
  41.          END
  42.  
  43.      The example above declares two public symbols using the 'C' naming
  44.      style (i.e. case sensitive with preceding underscores).  The public
  45.      symbols reference the two procedures.  The procedures are FAR, so the
  46.      C program must be compiled using the medium, large, or huge memory
  47.      models.
  48.  
  49.      When these macros are used, the result of the assembly is a valid
  50.      object module and may be linked using LINK.EXE, TLINK.EXE, or other
  51.      compatible linker.  For instance, the example above would be compiled
  52.      as follows:
  53.  
  54.        WASM myfile myfile.obj
  55.  
  56.                                    INIT Macro
  57.                                    ----------
  58.  
  59.      The INIT macro creates an object module header and defines the segment
  60.      in which to place the code and data.  The syntax for INIT is:
  61.  
  62.  
  63.        INIT name, segment, class, segtype
  64.  
  65.      The name is the name of the module.  Most compilers use the name of
  66.      the source file (including the extension) to name an object module.
  67.  
  68.      The segment is the name of the segment.  Depending on the compiler and
  69.      the memory model, it might be necessary to place code or data in
  70.      specific segments.  Compilers from Microsoft and Borland (and probably
  71.      most other vendors) place the code in segment '_TEXT' when using the
  72.      near code memory models (small and compact) and the data in segment
  73.      '_DATA' when using near data memory models (small and medium).
  74.      Usually any name is okay if the segment is private.
  75.  
  76.      The class is the name of the segment class.  The segment class
  77.      primarily affects the order of the segments.  You should use either
  78.      'CODE' if you are defining public routines or 'DATA' if you are
  79.      defining public data.  The class may be blank, in which case the
  80.      segment has no class:
  81.  
  82.          INIT    'MYFILE.ASM', '_TEXT', , ALIGN_BYTE+COMBINE_PUBLIC
  83.  
  84.      The segtype is the type of segment.  There are two values that must be
  85.      added together for this argument, the alignment and combine type.  The
  86.      possible alignment and combine values are:
  87.  
  88.        ALIGN_BYTE        byte aligned
  89.        ALIGN_WORD        word aligned
  90.        ALIGN_PARA        paragraph aligned
  91.        ALIGN_PAGE        page aligned
  92.  
  93.        COMBINE_PRIVATE   private segment
  94.        COMBINE_PUBLIC    public segment
  95.        COMBINE_STACK     stack segment
  96.        COMBINE_COMMON    common segment
  97.  
  98.      If you wish to declare and access local data in the segment, it will
  99.      probably be necessary to create a paragraph aligned private segment.
  100.  
  101.      Public procedures in private segments should be FAR and the language
  102.      must be compiled using a far code model -- either medium, large, or
  103.      huge.  When a routine accesses data in a private segment, the current
  104.      code segment should be used:
  105.  
  106.          BEGIN
  107.  
  108.        MyProc1 PROC FAR
  109.          push ds
  110.          mov ax, cs          ;load data segment from CS
  111.          mov ds, ax          ;
  112.          mov ax, data        ;now we can access data
  113.          pop ds
  114.          ret
  115.          ENDP
  116.  
  117.        data DW ?
  118.  
  119.          END
  120.  
  121.  
  122.  
  123.                                   PUBLIC Macro
  124.                                   ------------
  125.  
  126.      The PUBLIC macro creates public symbol definitions.  A symbol must be
  127.      public if it is to be used outside of the module.  The syntax for
  128.      PUBLIC is:
  129.  
  130.          PUBLIC symbol, name
  131.  
  132.      The symbol is a symbol from the assembler code or data to be made
  133.      public.  The name is the name to be used by other modules in accessing
  134.      the symbol.  Example:
  135.  
  136.          PUBLIC MyProc, 'MYPROC'
  137.  
  138.      In this example, references to MYPROC in other modules will access the
  139.      symbol MyProc in this module.
  140.  
  141.      Depending on the compiler and memory model, it may not be possible to
  142.      mix public references to code and data in one module.
  143.  
  144.                                 BEGIN/END Macros
  145.                                 ----------------
  146.  
  147.      The BEGIN macro must appear before all code and data and the END macro
  148.      must follow all code and data.  No code or data may appear outside of
  149.      the BEGIN and END macros.  The END macro is usually the final
  150.      statement of the source file.  BEGIN starts an object module data
  151.      record and sets the origin to zero.  END finishes the data record and
  152.      creates a module end record.
  153.  
  154.                              Language Considerations
  155.                              -----------------------
  156.  
  157.      There are certain conventions that must be followed when writing
  158.      subroutines for high level languages:
  159.  
  160.      1. The procedure type (NEAR or FAR) must match the memory model.
  161.         Procedures should be NEAR when using the small or compact memory
  162.         models.  Procedures should be FAR when using the medium, large, or
  163.         huge memory models.  Most languages that do not support explicit
  164.         memory models use far code segments, thus procedures should be FAR.
  165.  
  166.      2. Most languages use one of two different naming and parameter
  167.         passing conventions, 'C' or 'pascal' (even languages are not C or
  168.         Pascal).  'C' routines should be given a case sensitive name with a
  169.         leading underscore, expect their parameters to be pushed on the
  170.         stack in reverse order, and not pop parameters when exiting.
  171.         'pascal' routines should be given a case insensitive name (all
  172.         capital letters), expect their parameters to be pushed on the stack
  173.         in the order they appear in the source, and must pop all parameters
  174.         when exiting.
  175.  
  176.      Parameters are accessed via an offset from the stack pointer (SP).
  177.      This offset depends on the routine entry code and whether the
  178.      procedure is NEAR or FAR.
  179.  
  180.      Example:
  181.  
  182.  
  183.          PUBLIC MyProc, 'MYPROC'   ;'pascal' type public symbol
  184.        ; PUBLIC MyProc, '_MyProc'  ;'C' type public symbol
  185.  
  186.          BEGIN
  187.  
  188.        MyProc PROC NEAR      ;might also be FAR
  189.          push bp
  190.          mov bp, sp          ;get stack pointer
  191.          push di             ;other regs to save
  192.          push ds             ;
  193.  
  194.          mov ax, [bp+4]      ;first 'pascal' parameter, last 'C' parameter
  195.                              ;should be [BP+6] if FAR procedure
  196.  
  197.          mov bx, [bp+6]      ;next parameter
  198.                              ;should be [BP+8] if FAR procedure
  199.  
  200.          ;
  201.          ; rest of MyProc
  202.          ;
  203.  
  204.          pop ds
  205.          pop di
  206.          pop bp
  207.          ret 4               ;fix stack if 'pascal', otherwise just RET
  208.          ENDP
  209.  
  210.      The registers that must be saved by an assembler routine varies from
  211.      language to language.  Most compiler manuals describe the steps
  212.      necessary in writing and calling assembler routines.  It may also be
  213.      useful to look at a link map from the compiler and study an executable
  214.      program from the compiler using a debugger.
  215.  
  216.      You can write object modules for Turbo Pascal if you place the code in
  217.      the segment CODE and leave the class blank.  Since Turbo Pascal (at
  218.      least version 5.5) ignores the alignment and combine values, local
  219.      data cannot be accessed.
  220.  
  221.                                WASM Library Files
  222.                                ------------------
  223.  
  224.      The WASM library files may be used in modules as long as certain
  225.      conditions are met.  All library files assume that DS=ES=CS.  Library
  226.      files that require STACK.ASM assume that SS=DS=ES=CS, thus a separate
  227.      stack must be set up.  Some of the library files won't work in
  228.      modules, like PARMS.ASM, because the current segment is assumed to be
  229.      the PSP segment.  Since the library files produce code and data, the
  230.      library INCLUDE statements must be between the BEGIN and END.  Several
  231.      of the library files have startup code that should be executed, so you
  232.      might want to place the library INCLUDE statements within a special
  233.      initialization routine.  Note that WASM routines cannot call WASM
  234.      routines in other modules because WASM object modules do not support
  235.      external symbols.
  236.